home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Network Support Library
/
RoseWare - Network Support Library.iso
/
btrieve
/
btrv.txt
< prev
next >
Wrap
Text File
|
1993-02-27
|
23KB
|
675 lines
MARXMENU DATABASE FUNCTIONS
Well, after talking about it for years, version 2.42 now includes a
strong set of database tools. The database is based on Novell's Btrieve
interface. Thus it has the reliability of proven database technology. We
are pushing Btrieve to the limit and then some in order to get the
requirements needed from a database engine.
As of version 2.42 about 90% of the features of Btrieve have been
implemented in MarxMenu. So if you are familiar with Btrieve
already you will be able to do most things just like you're used to.
Btrieve is primarily a fixed length database engine with the ability to
add a single variable length field on the end of a record. When using
MarxMenu with Btrieve, we typically store MarxMenu style variables in
the variable length section and reserve the fixed length section for key
fields only. While we recommend you too consider this approach you are
free to develop and use any data models you prefer.
You will notice several unusual things about MarxMenu as a database.
We decided that the square model or relationally linked square model is
to limiting. You can do square model databases if you want to, but the
experience of getting rid of the square model is like an animal being
let out of a cage for the first time. It's a little scary at first.
When you create a MarxMenu Btrieve database you may define all your
fields, if you want, but you are only required to define the fields that
will be used as key fields. You will need to define the fields type, and
for key fields the key properties.
When data is written to a file the data is passed as a MarxMenu array.
The first elements of the array have to match the fixed potion of you
structure, normally your key fields. Any elements after the key fields
are written in MarxMenu format to the variable length section of the
record. Thus after the key fields you can do whatever you want. Here's a
list of some of the flexible features.
1) Records do not have to contain the same fields or the same number of
fields. You can have 20 fields in one record and 5 fields in the
next one. There are no rules that the data in one field of a record
has to be of the same data type as the same field of the previous
record.
2) Records can contain MarxMenu style arrays. Thus if you are using a
phone field as an array of phone numbers you can store as many phone
numbers in that field as you want. MarxMenu can support arrays
within arrays of up to 30 levels within a single record.
3) Since MarxMenu supports writing MarxMenu style variable structures
to database records, you need not have to specify the type of data,
the data size, or the structure of the data before you access the
file. If you want to write data you just do it.
Since this code is new you may want a lot of new features added to go
along with what's provided so far. Feel free to call with suggestions,
we are interested in hearing how this is working out for you.
Use of the Btreive commands require that you have Btrieve 6.0 or 5.10.
You will need to have Btrieve NLM running on the server and BRequest
running on the workstation to use this database. All the Btreive
database commands start with the BTRV prefix.
Only network versions of MarxMenu contain the BTRV database commands,
the single user version is not equiped with this feature.
BtrvAbortTransaction
BtrvAbortTransaction is used to about all changes to the file that have
occurred since the BtrvBeginTransaction was executed.
See Also: BtrvBeginTransaction, BtrvEndTransaction
Category: Btrieve
BtrvBeginTransaction
Betrieve supports a concept called transaction tracking. With
transaction tracking you can use the BtrvBeginTransaction command to set
a file condition flag marking the start of a file process. Should the
file process be interupted before the end of the process the files will
be restored to the original condition they were in prior to the
BtrvBeginTransaction.
See Also: BtrvAbortTransaction, BtrvEndTransaction
Category: Btrieve
BtrvClearOwner (Handle)
BtrvClearOwner clears the owner and allows normal access to the file.
Example:
BtrvClearOwner (Handle)
See Also: BtrvSetOwner
Category: Btrieve
BtrvClose (Handle)
BtrvClose closes the file. The parameter `Handle' is the file handle
returned from BtrvOpen.
Example:
BtrvClose (Handle)
See Also: BtrvOpen
Category: Btrieve
BtrvCreate (FileName,Fields)
BtrvCreate is the most complicated Btrieve call. It defines the creation
of the Btrieve database. The fields parameter is a two dimensional
MarxMenu array that describes the fields in the file. It is designed to
support either standard Btrieve fixed length fields or MarxMenu key
fields. Using MarxMenu fields is the easiest because you only have to
define the key fields. Non-Key fields do not have to be predefined.
The easiest way to define these fields is to create a comma delimited
text file and use ReadAscTextFile('FIELDS.TXT',Fields). This will create
the array needed by BtrvCreate. The text file might look as follows:
Name,String,35,Key,DUP,MOD,UPPER,DEC
CustomerNumber,Auto
From,String,35
Password,String,15
Access,Num
Flags,String,10
FirstDate,Date
LastDate,Date
Calls,Num
CallTime,Time
Phone,String,15
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
BtrvCreate('BBSUSER.BTD',Fields)
The above example creates a conventional fixed length database with one
key field, the "name" field. Each line in the defination file defines a
new field. Each line has at least two parameters. The first parameter is
the field name. It is followed by the field type. There are five legal
field types. They are:
String - Containes alphanumeric strings. String fields have a required
third parameter, the maximum length of the string. In the
above example the "Name" and "From" fields both have max
lengths of 35 characters.
Num - Integer numeric fields. This field type supports storing
integer numbers.
Date - Dates fields. The DOS country code is automatically supported
to establish date format. If not specified, the default
format is "MM/DD/YY".
Time - Time fields. This command also reads the DOS country code to
establish the proper format. Otherwise default is "HH:MM:SS".
Auto - Auto increment fields. This field is used to maintain field
counters. This field is more complicated than most. Normally
in your record mask you should provide a value of zero, this
will cause the value stored in the file to be one more than
the value stored in the last record. You can, however,
provide a mask containing a specific number. If that number
does not already exist anywhere in this field then it will be
stored. If it does exist, a Btreive error will result.
USING KEY FIELDS
Key fields are fields that are have internal lookup indexs automatically
defined and maintained by the Btreive system. If you want to use the
intelligent loopup `BtrvGet_____' series of commands then the field you
reference must be a key field. You define a key field by adding the
parameter "KEY" as the third parameter on the field defination line.
When specifying a field as a key field you have four optional
configuration parameters, as seen in the previous example. They are:
DUP - {Duplicates} This permits the field to have duplicate values
in multiple records. If this parameter is not specified then no
two records may have the same value in the affected field. In
reality, you will almost always specify this parameter when
defining a key field.
MOD - {Modifyable} This allows existing existing field records to be
modifyed. If this parameter is not specified then once a record
is written, the affected field is set in stone and changes are
not permitted.
UPPER- {UpperCase Only} Used in cunjunction with string fields only,
this will force all text information to be stored as UPPERCASE.
DEC - {Decending Order} This caused the key stored in the affected
field to be maintained in reverse order.
If you wanted to use a MarxMenu style database then only the first line
of the above example need be in the file. This would create a file with
a single fixed length key field and put the rest of the fields in the
variable length section. Using the MarxMenu style you can pass anything
you want for the rest of the fields.
Category: Btrieve
BtrvDelete (Handle)
BtrvDelete deletes a record from a data file at the location of the last
data read from the file.
Example:
BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)
BtrvDelete(Handle)
See Also: BtrvInsert
Category: Btrieve
BtrvEndTransaction
BtrvEndTransaction is used at the end of a transaction tracking process.
This command updates the files with all the data to be written. Refer to
the BtrvBeginTransaction command for additional information.
See Also: BtrvAbortTransaction, BtrvBeginTransaction
Category: Btrieve
BtrvGetEqual (DataVar,Value,Key,Handle)
BtrvGetEqual goes to the previous record of the file based on the key
number that you pass and reads the record matching Value into DataVar.
The type of Value passed has to match the type of data the key for which
the key is defined. If the key is a string then Value is a string. If
BtrvResult is zero, the data was found. If BtrvGetNext is called after
this, the next sequential record based on the key is read.
Example:
BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)
See Also: BtrvGetLess, BtrvGetLessOrEqu, BtrvGetGreater
See Also: BtrvGetGreaterOrEqu
Category: Btrieve
BtrvGetFirst (DataVar,Key,Handle)
BtrvGetFirst goes to the first record of the file based on the key
number that you pass and reads the record into DataVar. This allows you
to access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('BBSUSER.BTD',Fields)
BtrvGetFirst(DataVar,1,Handle)
while BrtvResult = 0
loop DataVar
Write DataVar[LoopIndex] ' '
endloop
Writeln
BtrvGetNext(DataVar,1,Handle)
EndWhile
This example dumps the contents of a file to the screen.
See Also: BtrvGetLast, BtrvGetNext, BtrvGetPrev
Category: Btrieve
BtrvGetGreater (DataVar,Value,Key,Handle)
BtrvGetGreater goes to the next larger record of the file based on the
key number that you pass and reads the record greater than Value into
DataVar. The type of Value passed has to match the type of data the key
for which the key is defined. If the key is a string then Value is a
string. If BtrvResult is zero, the data was found. If BtrvGetPrev is
called after this, the next sequential record based on the key is read.
Example:
BtrvGetLess(DataVar,'MARC PERKEL',1,Handle)
See Also: BtrvGetEqual, BtrvGetLess, BtrvGetLessOrEqu
See Also: BtrvGetGreaterOrEqu
Category: Btrieve
BtrvGetGreaterOrEqu (DataVar,Value,Key,Handle)
BtrvGetGreaterOrEqu goes to the next larger or equal record of the file
based on the key number that you pass and reads the record greater than
or equal to Value into DataVar. The type of Value passed has to match
the type of data the key for which the key is defined. If the key is a
string then Value is a string. If BtrvResult is zero, the data was
found. If BtrvGetPrev is called after this, the next sequential record
based on the key is read.
Example:
BtrvGetLessOrEqu(DataVar,'MARC PERKEL',1,Handle)
See Also: BtrvGetEqual, BtrvGetLess, BtrvGetLessOrEqu, BtrvGetGreater
Category: Btrieve
BtrvGetLast (DataVar,Key,Handle)
BtrvGetLast goes to the last record of the file based on the key number
that you pass and reads the record into DataVar. This allows you to
access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('BBSUSER.BTD',Fields)
BtrvGetLast(DataVar,1,Handle)
while BrtvResult = 0
loop DataVar
Write DataVar[LoopIndex] ' '
endloop
Writeln
BtrvGetPrev(DataVar,1,Handle)
EndWhile
This example dumps the contents of a file to the screen backwards.
See Also: BtrvGetFirst, BtrvGetNext, BtrvGetPrev
Category: Btrieve
BtrvGetLess (DataVar,Value,Key,Handle)
BtrvGetLess goes to the next smaller record of the file based on the key
number that you pass and reads the record less than Value into DataVar.
The type of Value passed has to match the type of data the key for which
the key is defined. If the key is a string then Value is a string. If
BtrvResult is zero, the data was found. If BtrvGetPrev is called after
this, the next sequential record based on the key is read.
Example:
BtrvGetLess(DataVar,'MARC PERKEL',1,Handle)
See Also: BtrvGetEqual, BtrvGetLessOrEqu, BtrvGetGreater
See Also: BtrvGetGreaterOrEqu
Category: Btrieve
BtrvGetLessOrEqu (DataVar,Value,Key,Handle)
BtrvGetLessOrEqu goes to the next smaller or equal record of the file
based on the key number that you pass and reads the record less than or
equal to Value into DataVar. The type of Value passed has to match the
type of data the key for which the key is defined. If the key is a
string then Value is a string. If BtrvResult is zero, the data was
found. If BtrvGetPrev is called after this, the next sequential record
based on the key is read.
Example:
BtrvGetLessOrEqu(DataVar,'MARC PERKEL',1,Handle)
See Also: BtrvGetEqual, BtrvGetLess, BtrvGetGreater, BtrvGetGreaterOrEqu
Category: Btrieve
BtrvGetNext (DataVar,Key,Handle)
BtrvGetNext goes to the next record of the file based on the key number
that you pass and reads the record into DataVar. This allows you to
access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.
See Also: BtrvGetFirst, BtrvGetLast, BtrvGetPrev
Category: Btrieve
BtrvGetPrev (DataVar,Key,Handle)
BtrvGetPrev goes to the previous record of the file based on the key
number that you pass and reads the record into DataVar. This allows you
to access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.
See Also: BtrvGetFirst, BtrvGetLast, BtrvGetNext
Category: Btrieve
BtrvIndexes (Handle) : Number
BtrvIndexes returns the number of key fields in a file. You must open
the file and get a file handle first.
Example:
Writeln BtrvIndexes (Handle)
Category: Btrieve
BtrvInsert (DataVar,Handle)
BtrvInsert adds a new record to the data file. The data is passed in the
array DataVar. If key fields are used, or if you are using traditional
style fixed length fields, then the first elements of the array must
match the data structure of the file you defined with BtrvCreate. All
elements of the array after these fields are written to the variable
length part of the file. The variable length part can contain MarxMenu
multi-dimensional data structures.
Example:
BtrvInsert(DataVar,Handle)
See Also: BtrvDelete
Category: Btrieve
BtrvOpen (FileName,Fields) : Handle
BtrvOpen is used to open the file for access. Since Btrieve files do not
store a list of fields you have to pass the same data structure you did
when you created the file. If successful, BtrvOpen will return a file
handle. This handle will be referenced by all other commands that access
this file.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('BBSUSER.BTD',Fields)
If BtrvResult<>0
WriteLn "Btrieve Error: " BtrvResult " While Opening File."
EndIf
See Also: BtrvClose, BtrvCreate
Category: Btrieve
BtrvPageSize (Handle) : Number
BtrvPageSize returns the page size of in a file. You must open the file
and get a file handle first. The page size is the amount of disk space
allocated when a file is extended.
Example:
Writeln BtrvPageSize (Handle)
Category: Btrieve
BtrvRecLen (Handle) : Number
BtrvRecLen returns the size of the fixed length part of in a file. You
must open the file and get a file handle first.
Example:
Writeln BtrvRecLen (Handle)
Category: Btrieve
BtrvRecords (Handle) : Number
BtrvRecords returns the number of records in a file. You must open the
file and get a file handle first.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('CLIENTS.BTR',Fields)
Writeln BtrvRecords (Handle) ;# of Records in CLIENTS.BTR
Category: Btrieve
BtrvReset
BtrvReset is used to clear all transactions and close all files. It's a
good idea to start your programs with this command to clear any locks
that might be left out there from other programs that might have
aborted.
Example:
var fields
btrvreset ;Start with a clean slate!
readasctextfile('db.txt',fields) ;Get field Definitions
btrvcreate('phone.mb',fields) ;Create Btrieve File
writeln btrvresult ;Check for ok
Category: Btrieve
BtrvResult : Number
BtrvResult returns the result code from the last Btrieve call. A zero is
considered a success.
Example:
Procedure BtrieveError
If BtrvResult <> 0
Writeln 'Btrieve Error #',BtrvResult
Writeln 'Exiting Program...'
ExitMenu
EndIf
EndProc
See Also: BtrvResultMessage
Category: Btrieve
BtrvResultMessage : String
BtrvResultMessage automatically returns a string containing an error
message based on the value BtrvResult.
Example:
Writeln BtrvResultMessage ;write Btreive Error Message
See Also: BtrvResult
Category: Btrieve
BtrvSetOwner (Owner,Mode,Handle)
BtrvSetOwner is really a set password function. It restricts access to
the file unless you pass the owners name by setting BtrvOwner. The mode
controls access and data encryption as follows:
0 : No Btreive access - File Not Encrypted
1 : Read Only access - File Not Encrypted
2 : No Btreive access - File Encrypted
3 : Read Only access - File Encrypted
Example:
BtrvSetOwner('NERD',3,Handle)
See Also: BtrvClearOwner
Category: Btrieve
BtrvStepFirst (DataVar,Handle)
BtrvStepFirst goes to the first physical record of the file and reads
the record into DataVar. DataVar is a MarxMenu variable and the data
read creates an array of the fields stored on disk.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('BBSUSER.BTD',Fields)
BtrvStepFirst(DataVar,Handle)
while BrtvResult = 0
loop DataVar
Write DataVar[LoopIndex] ' '
endloop
Writeln
BtrvStepNext(DataVar,Handle)
EndWhile
This example dumps the contents of a file to the screen.
See Also: BtrvStepLast, BtrvStepNext, BtrvStepPrev
Category: Btrieve
BtrvStepLast (DataVar,Handle)
BtrvStepLast goes to the last physical record of the file and reads the
record into DataVar. DataVar is a MarxMenu variable and the data read
creates an array of the fields stored on disk.
Example:
ReadAscTextFile('FIELDS.TXT',Fields)
Handle = BtrvOpen('BBSUSER.BTD',Fields)
BtrvStepLast(DataVar,Handle)
while BrtvResult = 0
loop DataVar
Write DataVar[LoopIndex] ' '
endloop
Writeln
BtrvStepPrev(DataVar,Handle)
EndWhile
This example dumps the contents of a file to the screen backwards.
See Also: BtrvStepFirst, BtrvStepNext, BtrvStepPrev
Category: Btrieve
BtrvStepNext (DataVar,Handle)
BtrvStepNext goes to the next physical record of the file and reads the
record into DataVar. DataVar is a MarxMenu variable and the data read
creates an array of the fields stored on disk. This is normally used to
work through a file when the search field in not a key field.
Example:
var fields,temp,handle,vararray
readasctextfile('data.txt',fields)
handle=btrvopen('phone.mxb',fields)
while btrvresult=0
btrvstepnext(vararray,handle) ;<- Step to next file record
writeln vararray[1] " " vararray[2]
endwhile
btrvclose(handle)
See Also: BtrvStepFirst, BtrvStepLast, BtrvStepPrev
Category: Btrieve
BtrvStepPrev (DataVar,Handle)
BtrvStepPrev goes to the previous physical record of the file and reads
the record into the variable DataVar. DataVar is a MarxMenu variable and
the data read creates an array of the fields stored on disk.
See Also: BtrvStepFirst, BtrvStepLast, BtrvStepNext
Category: Btrieve
BtrvStop
BtrvStop is used to unload BTRIEVE.EXE or BREQUEST.EXE from memory. You
can load the requestor before running MarxMenu as a database and unload
the requestor when you are finished. This reclaims the memory the
requestor was using.
Category: Btrieve
BtrvUnusedPages (Handle) : Number
BtrvUnusedPages returns the number of unused pages in a file. You must
open the file and get a file handle first. Unused pages are created when
data is deleted from a file.
Example:
Writeln BtrvPageSize (Handle)
Category: Btrieve
BtrvUpdate (DataVar,Handle)
BtrvUpdate changes a record in the data file at the last location
accessed with any command that reads a record. The data is passed in the
array DataVar. If key fields are used, or if you are using traditional
style fixed length fields, then the first elemebts of the array must
match the data structure of the file you defined with BtrvCreate. All
elements of the array after these fields are written to the variable
length part of the file. The variable length part can contain MarxMenu
multi-dimensional data structures.
Example:
BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)
if BtrvResult = 0
DataVar[3] = 37
BtrvUpdate(DataVar,Handle)
endif
Category: Btrieve
BtrvVersion : Number
BtrvVersion returns a number representing the version number of Btrieve
that you are using. A zero indicates that Btrieve is not installed. If
Btrieve is installed then it returns 100 times the version number plus
the minor version number. Version 6.0 becomes 600. Version 5.10 becomes
510.
Example:
if BtrieveVersion = 0
Writeln "Sorry, but Btrieve must be loaded first!"
else
Writeln "You are running Btrieve Version #: " BtrvVersion
endif
Category: Btrieve